home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / NameRegistry.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  13.3 KB  |  486 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1993-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __NAMEREGISTRY__
  19. #define __NAMEREGISTRY__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24.  
  25.  
  26.  
  27. #if PRAGMA_ONCE
  28. #pragma once
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_STRUCT_ALIGN
  40.     #pragma options align=power
  41. #elif PRAGMA_STRUCT_PACKPUSH
  42.     #pragma pack(push, 2)
  43. #elif PRAGMA_STRUCT_PACK
  44.     #pragma pack(2)
  45. #endif
  46.  
  47. /*******************************************************************************
  48.  * 
  49.  * Foundation Types
  50.  *
  51.  */
  52. /* Value of a property */
  53. typedef void *                            RegPropertyValue;
  54. /* Length of property value */
  55. typedef UInt32                             RegPropertyValueSize;
  56. /*******************************************************************************
  57.  * 
  58.  * RegEntryID    :    The Global x-Namespace Entry Identifier
  59.  *
  60.  */
  61. struct RegEntryID {
  62.     UInt32                             contents[4];
  63. };
  64. typedef struct RegEntryID RegEntryID;
  65.  
  66. typedef RegEntryID *                    RegEntryIDPtr;
  67. /*******************************************************************************
  68.  *
  69.  * Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  70.  *
  71.  *    • Names are a colon-separated list of name components.  Name components
  72.  *      may not themselves contain colons.  
  73.  *    • Names are presented as null-terminated ASCII character strings.
  74.  *    • Names follow similar parsing rules to Apple file system absolute
  75.  *      and relative paths.  However the '::' parent directory syntax is
  76.  *      not currently supported.
  77.  */
  78. /* Max length of Entry Name */
  79.  
  80. enum {
  81.     kRegCStrMaxEntryNameLength    = 47
  82. };
  83.  
  84. /* Entry Names are single byte ASCII */
  85. typedef char                             RegCStrEntryName;
  86. typedef char *                            RegCStrEntryNamePtr;
  87. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  88. typedef char                             RegCStrEntryNameBuf[48];
  89. typedef char                             RegCStrPathName;
  90. typedef UInt32                             RegPathNameSize;
  91.  
  92. enum {
  93.     kRegPathNameSeparator        = ':',                            /* 0x3A */
  94.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  95.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  96. };
  97.  
  98. /*******************************************************************************
  99.  *
  100.  * Property Name and ID Definitions
  101.  *    (Applies to all Properties Regardless of NameSpace)
  102.  */
  103.  
  104. enum {
  105.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  106.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  107. };
  108.  
  109. typedef char                             RegPropertyNameBuf[32];
  110. typedef char                             RegPropertyName;
  111. typedef char *                            RegPropertyNamePtr;
  112. /*******************************************************************************
  113.  *
  114.  * Iteration Operations
  115.  *
  116.  *    These specify direction when traversing the name relationships
  117.  */
  118. typedef UInt32                             RegIterationOp;
  119. typedef RegIterationOp                     RegEntryIterationOp;
  120.  
  121. enum {
  122.                                                                 /* Absolute locations*/
  123.     kRegIterRoot                = 0x00000002,                    /* "Upward" Relationships    */
  124.     kRegIterParents                = 0x00000003,                    /* include all  parent(s) of entry */
  125.                                                                 /* "Downward" Relationships*/
  126.     kRegIterChildren            = 0x00000004,                    /* include all children */
  127.     kRegIterSubTrees            = 0x00000005,                    /* include all sub trees of entry */
  128.     kRegIterDescendants            = 0x00000005,                    /* include all descendants of entry */
  129.                                                                 /* "Horizontal" Relationships    */
  130.     kRegIterSibling                = 0x00000006,                    /* include all siblings */
  131.                                                                 /* Keep doing the same thing*/
  132.     kRegIterContinue            = 0x00000001
  133. };
  134.  
  135. /*******************************************************************************
  136.  *
  137.  * Name Entry and Property Modifiers
  138.  *
  139.  *
  140.  *
  141.  * Modifiers describe special characteristics of names
  142.  * and properties.  Modifiers might be supported for
  143.  * some names and not others.
  144.  * 
  145.  * Device Drivers should not rely on functionality
  146.  * specified as a modifier.
  147.  */
  148. typedef UInt32                             RegModifiers;
  149. typedef RegModifiers                     RegEntryModifiers;
  150. typedef RegModifiers                     RegPropertyModifiers;
  151.  
  152. enum {
  153.     kRegNoModifiers                = 0x00000000,                    /* no entry modifiers in place */
  154.     kRegUniversalModifierMask    = 0x0000FFFF,                    /* mods to all entries */
  155.     kRegNameSpaceModifierMask    = 0x00FF0000,                    /* mods to all entries within namespace */
  156.     kRegModifierMask            = (long)0xFF000000                /* mods to just this entry */
  157. };
  158.  
  159. /* Universal Property Modifiers */
  160.  
  161. enum {
  162.     kRegPropertyValueIsSavedToNVRAM = 0x00000020,                /* property is non-volatile (saved in NVRAM) */
  163.     kRegPropertyValueIsSavedToDisk = 0x00000040                    /* property is non-volatile (saved on disk) */
  164. };
  165.  
  166. /* ///////////////////////
  167. //
  168. // The Registry API
  169. //
  170. /////////////////////// */
  171. /* ///////////////////////
  172. //
  173. // Entry Management
  174. //
  175. /////////////////////// */
  176.  
  177. /*-------------------------------
  178.  * EntryID handling
  179.  */
  180. /*
  181.  * Initialize an EntryID to a known invalid state
  182.  *   note: invalid != uninitialized
  183.  */
  184. EXTERN_API_C( OSStatus )
  185. RegistryEntryIDInit                (RegEntryID *            id);
  186.  
  187. /*
  188.  * Compare EntryID's for equality or if invalid
  189.  *
  190.  * If a NULL value is given for either id1 or id2, the other id 
  191.  * is compared with an invalid ID.  If both are NULL, the id's 
  192.  * are consided equal (result = true). 
  193.  */
  194. EXTERN_API_C( Boolean )
  195. RegistryEntryIDCompare            (const RegEntryID *        id1,
  196.                                  const RegEntryID *        id2);
  197.  
  198. /*
  199.  * Copy an EntryID
  200.  */
  201. EXTERN_API_C( OSStatus )
  202. RegistryEntryIDCopy                (const RegEntryID *        src,
  203.                                  RegEntryID *            dst);
  204.  
  205. /*
  206.  * Free an ID so it can be reused.
  207.  */
  208. EXTERN_API_C( OSStatus )
  209. RegistryEntryIDDispose            (RegEntryID *            id);
  210.  
  211. /*-------------------------------
  212.  * Adding and removing entries
  213.  *
  214.  * If (parentEntry) is NULL, the name is assumed
  215.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  216.  */
  217. EXTERN_API_C( OSStatus )
  218. RegistryCStrEntryCreate            (const RegEntryID *        parentEntry,
  219.                                  const RegCStrPathName * name,
  220.                                  RegEntryID *            newEntry);
  221.  
  222. EXTERN_API_C( OSStatus )
  223. RegistryEntryDelete                (const RegEntryID *        id);
  224.  
  225. /*---------------------------
  226.  * Traversing the namespace
  227.  *
  228.  * To support arbitrary namespace implementations in the future,
  229.  * I have hidden the form that the place pointer takes.  The previous
  230.  * interface exposed the place pointer by specifying it as a
  231.  * RegEntryID.
  232.  *
  233.  * I have also removed any notion of returning the entries
  234.  * in a particular order, because an implementation might
  235.  * return the names in semi-random order.  Many name service
  236.  * implementations will store the names in a hashed lookup
  237.  * table.
  238.  *
  239.  * Writing code to traverse some set of names consists of
  240.  * a call to begin the iteration, the iteration loop, and
  241.  * a call to end the iteration.  The begin call initializes
  242.  * the iteration cookie data structure.  The call to end the 
  243.  * iteration should be called even in the case of error so 
  244.  * that allocated data structures can be freed.
  245.  *
  246.  *    Create(...)
  247.  *    do {
  248.  *        Iterate(...);
  249.  *    } while (!done);
  250.  *    Dispose(...);
  251.  *
  252.  * This is the basic code structure for callers of the iteration
  253.  * interface.
  254.  */
  255.  
  256. typedef struct OpaqueRegEntryIter*         RegEntryIter;
  257. /* 
  258.  * create/dispose the iterator structure
  259.  *   defaults to root with relationship = kRegIterDescendants
  260.  */
  261. EXTERN_API_C( OSStatus )
  262. RegistryEntryIterateCreate        (RegEntryIter *            cookie);
  263.  
  264. EXTERN_API_C( OSStatus )
  265. RegistryEntryIterateDispose        (RegEntryIter *            cookie);
  266.  
  267. /* 
  268.  * set Entry Iterator to specified entry
  269.  */
  270. EXTERN_API_C( OSStatus )
  271. RegistryEntryIterateSet            (RegEntryIter *            cookie,
  272.                                  const RegEntryID *        startEntryID);
  273.  
  274. /*
  275.  * Return each value of the iteration
  276.  *
  277.  * return entries related to the current entry
  278.  * with the specified relationship
  279.  */
  280. EXTERN_API_C( OSStatus )
  281. RegistryEntryIterate            (RegEntryIter *            cookie,
  282.                                  RegEntryIterationOp     relationship,
  283.                                  RegEntryID *            foundEntry,
  284.                                  Boolean *                done);
  285.  
  286. /*
  287.  * return entries with the specified property
  288.  *
  289.  * A NULL RegPropertyValue pointer will return an
  290.  * entry with the property containing any value.
  291.  */
  292. EXTERN_API_C( OSStatus )
  293. RegistryEntrySearch                (RegEntryIter *            cookie,
  294.                                  RegEntryIterationOp     relationship,
  295.                                  RegEntryID *            foundEntry,
  296.                                  Boolean *                done,
  297.                                  const RegPropertyName * propertyName,
  298.                                  const void *            propertyValue,
  299.                                  RegPropertyValueSize     propertySize);
  300.  
  301. /*--------------------------------
  302.  * Find a name in the namespace
  303.  *
  304.  * This is the fast lookup mechanism.
  305.  * NOTE:  A reverse lookup mechanism
  306.  *      has not been provided because
  307.  *        some name services may not
  308.  *        provide a fast, general reverse
  309.  *        lookup.
  310.  */
  311. EXTERN_API_C( OSStatus )
  312. RegistryCStrEntryLookup            (const RegEntryID *        searchPointID,
  313.                                  const RegCStrPathName * pathName,
  314.                                  RegEntryID *            foundEntry);
  315.  
  316. /*---------------------------------------------
  317.  * Convert an entry to a rooted name string
  318.  *
  319.  * A utility routine to turn an Entry ID
  320.  * back into a name string.
  321.  */
  322. EXTERN_API_C( OSStatus )
  323. RegistryEntryToPathSize            (const RegEntryID *        entryID,
  324.                                  RegPathNameSize *        pathSize);
  325.  
  326. EXTERN_API_C( OSStatus )
  327. RegistryCStrEntryToPath            (const RegEntryID *        entryID,
  328.                                  RegCStrPathName *        pathName,
  329.                                  RegPathNameSize         pathSize);
  330.  
  331. /*
  332.  * Parse a path name.
  333.  *
  334.  * Retrieve the last component of the path, and
  335.  * return a spec for the parent.
  336.  */
  337. EXTERN_API_C( OSStatus )
  338. RegistryCStrEntryToName            (const RegEntryID *        entryID,
  339.                                  RegEntryID *            parentEntry,
  340.                                  RegCStrEntryName *        nameComponent,
  341.                                  Boolean *                done);
  342.  
  343. /* //////////////////////////////////////////////////////
  344. //
  345. // Property Management
  346. //
  347. ////////////////////////////////////////////////////// */
  348. /*-------------------------------
  349.  * Adding and removing properties
  350.  */
  351. EXTERN_API_C( OSStatus )
  352. RegistryPropertyCreate            (const RegEntryID *        entryID,
  353.                                  const RegPropertyName * propertyName,
  354.                                  const void *            propertyValue,
  355.                                  RegPropertyValueSize     propertySize);
  356.  
  357. EXTERN_API_C( OSStatus )
  358. RegistryPropertyDelete            (const RegEntryID *        entryID,
  359.                                  const RegPropertyName * propertyName);
  360.  
  361. /*---------------------------
  362.  * Traversing the Properties of a name
  363.  *
  364.  */
  365. typedef struct OpaqueRegPropertyIter*     RegPropertyIter;
  366. EXTERN_API_C( OSStatus )
  367. RegistryPropertyIterateCreate    (const RegEntryID *        entry,
  368.                                  RegPropertyIter *        cookie);
  369.  
  370. EXTERN_API_C( OSStatus )
  371. RegistryPropertyIterateDispose    (RegPropertyIter *        cookie);
  372.  
  373. EXTERN_API_C( OSStatus )
  374. RegistryPropertyIterate            (RegPropertyIter *        cookie,
  375.                                  RegPropertyName *        foundProperty,
  376.                                  Boolean *                done);
  377.  
  378. /*
  379.  * Get the value of the specified property for the specified entry.
  380.  *
  381.  */
  382. EXTERN_API_C( OSStatus )
  383. RegistryPropertyGetSize            (const RegEntryID *        entryID,
  384.                                  const RegPropertyName * propertyName,
  385.                                  RegPropertyValueSize *    propertySize);
  386.  
  387. /*
  388.  * (*propertySize) is the maximum size of the value returned in the buffer
  389.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  390.  * value returned.
  391.  */
  392. EXTERN_API_C( OSStatus )
  393. RegistryPropertyGet                (const RegEntryID *        entryID,
  394.                                  const RegPropertyName * propertyName,
  395.                                  void *                    propertyValue,
  396.                                  RegPropertyValueSize *    propertySize);
  397.  
  398. EXTERN_API_C( OSStatus )
  399. RegistryPropertySet                (const RegEntryID *        entryID,
  400.                                  const RegPropertyName * propertyName,
  401.                                  const void *            propertyValue,
  402.                                  RegPropertyValueSize     propertySize);
  403.  
  404. /* //////////////////////////////////////////////////////
  405. //
  406. // Modibute (err, I mean Modifier) Management
  407. //
  408. ////////////////////////////////////////////////////// */
  409. /*
  410.  * Modifiers describe special characteristics of names
  411.  * and properties.  Modifiers might be supported for
  412.  * some names and not others.
  413.  * 
  414.  * Device Drivers should not rely on functionality
  415.  * specified as a modifier.  These interfaces
  416.  * are for use in writing Experts.
  417.  */
  418. /*
  419.  * Get and Set operators for entry modifiers
  420.  */
  421. EXTERN_API_C( OSStatus )
  422. RegistryEntryGetMod                (const RegEntryID *        entry,
  423.                                  RegEntryModifiers *    modifiers);
  424.  
  425. EXTERN_API_C( OSStatus )
  426. RegistryEntrySetMod                (const RegEntryID *        entry,
  427.                                  RegEntryModifiers         modifiers);
  428.  
  429. /*
  430.  * Get and Set operators for property modifiers
  431.  */
  432. EXTERN_API_C( OSStatus )
  433. RegistryPropertyGetMod            (const RegEntryID *        entry,
  434.                                  const RegPropertyName * name,
  435.                                  RegPropertyModifiers *    modifiers);
  436.  
  437. EXTERN_API_C( OSStatus )
  438. RegistryPropertySetMod            (const RegEntryID *        entry,
  439.                                  const RegPropertyName * name,
  440.                                  RegPropertyModifiers     modifiers);
  441.  
  442. /*
  443.  * Iterator operator for entry modifier search
  444.  */
  445. EXTERN_API_C( OSStatus )
  446. RegistryEntryMod                (RegEntryIter *            cookie,
  447.                                  RegEntryIterationOp     relationship,
  448.                                  RegEntryID *            foundEntry,
  449.                                  Boolean *                done,
  450.                                  RegEntryModifiers         matchingModifiers);
  451.  
  452. /*
  453.  * Iterator operator for entries with matching 
  454.  * property modifiers
  455.  */
  456. EXTERN_API_C( OSStatus )
  457. RegistryEntryPropertyMod        (RegEntryIter *            cookie,
  458.                                  RegEntryIterationOp     relationship,
  459.                                  RegEntryID *            foundEntry,
  460.                                  Boolean *                done,
  461.                                  RegPropertyModifiers     matchingModifiers);
  462.  
  463.  
  464.  
  465.  
  466. #if PRAGMA_STRUCT_ALIGN
  467.     #pragma options align=reset
  468. #elif PRAGMA_STRUCT_PACKPUSH
  469.     #pragma pack(pop)
  470. #elif PRAGMA_STRUCT_PACK
  471.     #pragma pack()
  472. #endif
  473.  
  474. #ifdef PRAGMA_IMPORT_OFF
  475. #pragma import off
  476. #elif PRAGMA_IMPORT
  477. #pragma import reset
  478. #endif
  479.  
  480. #ifdef __cplusplus
  481. }
  482. #endif
  483.  
  484. #endif /* __NAMEREGISTRY__ */
  485.  
  486.